home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1995…tember: Reference Library / Dev.CD Sep 95 RL / Dev.CD Sep 95 RL.toast / mac / Technical Documentation / develop / develop Issue 22 code / PCI Driver Sample / Framework NCR Sample ReadMe next >
Encoding:
Text File  |  1995-07-27  |  6.8 KB  |  159 lines  |  [TEXT/ttxt]
  1. This is a sample driver for an asynchronous hardware device - in this
  2. case, an NCR 8250 PCI interface card that uses an NCR 53C825 SCSI
  3. interface chip. The driver sources are separated into three generally
  4. independent areas: device driver mainline, hardware-specific interface,
  5. and utilities for a number of driver services, including the Expansion
  6. Bus Manager and the Name Registry. The driver illustrates I/O request
  7. management, DMA setup and operation, device configuration. It also
  8. shows one approach to debugging asynchronous applications; but
  9. probably not the best.
  10.  
  11. Although this is a working driver, it has received only a bare minimum
  12. of testing (as shown by the TestDriver utility). It is not intended as
  13. a sample for programming the NCR 8250 PCI interface card. Also, it
  14. should not be used as a basis for SCSI driver development: SCSI device
  15. drivers should use the SCSI Manager interface, and SCSI host bus
  16. adaptors should be written as SIMS.
  17.  
  18. There are "quick-and-dirty" ports of two SCSI test utilities that
  19. have not been completely moved to the NCR environment (in particular,
  20. some dialog and menu options are present that don't make sense for
  21. the NCR driver. These are probably unnecessary for others. The
  22. asynchronous test, however, might be useful for driver stress testing.
  23.  
  24. Build instructions (A5 release and later)
  25.  
  26. 1. Copy the Framework NCR Sample folder from the DDK CD to the
  27. top-level of your system disk (or another disk if appropriate).
  28. 2. Copy the PCICIncludes folder from the DDK CD to the top-level
  29. of the disk you chose in step 1 above.
  30. 3. Copy the PCILibraries folder from the DDK CD to the top-level
  31. of the disk you chose in step 1 above.
  32. 4. If you want to use the logging functions, copy the LogLibrary
  33. shared library to the Extensions folder, and add the dcmd to the
  34. MacsBug Prefs file. If you don't, disable LogLibrary and edit out
  35. any calls that are not resolved. The LogLibrary is in the debugging
  36. utilities folder.
  37.  
  38. This disk will have the following general organization:
  39.   Disk
  40.   : Framework NCR Sample (folder)
  41.     : NCR_DriverProject (folder)
  42.     : NCR_TestAppProject (folder)
  43.   : PCICincludes
  44.   : PCILibraries
  45.  
  46. 4. Copy the UserStartup•PCI file from the FrameWork NCR Sample folder
  47. on the DDK CD to the Preferences folder of your System boot disk.
  48. Edit the UserStartup•PCI file to define the {PCICIncludes} and
  49. {PCILibraries} MPW exported variables.
  50.  
  51. 5. To build under MetroWerks, you may need to reset the path names
  52. in the Preferences dialog under the AccessPaths sub-heading. You need
  53. to do this for both projects (NCRDriver.Δ and TestDriver.Δ). You may
  54. also need to "refresh" the MetroWerks project by manually removing
  55. libraries and adding fresh copies.
  56.  
  57. 6. You should then be able to build the MPW version of the driver. The
  58. test application currently only builds under Metrowerks, but conversion
  59. to MPW should prove straightforward.
  60.  
  61. Changes since the A2 release
  62.  
  63. •• Framework driver
  64. • The Framework driver was extensively revised (see the comments
  65.    in DoDriverIO.c for details). This includes folder reorganization
  66.    and other mechanical changes required by the changes to headers
  67.    and libraries.
  68. • The Framework driver now supports supersede/replace, but this
  69.    has not been tested by actually replacing a driver.
  70. • Corrected an error where it only did I/O cycles to base address
  71.    zero. This works as long as the NCR card was the only external
  72.    device. Now, the I/O cycle base address is retrieved from the
  73.    Name Registry.
  74. • Corrected a potential error by adding SynchonizeIO calls in the
  75.    hardware-access routines. Also, marked some variables with
  76.    the "volatile" C keyword to prevent over-optomization.
  77. • Added simple support for PrepareMemoryForIO. This is limited
  78.    to a single physical page, but does illustrate how the function
  79.    is to be used.
  80. • The driver stores the Initiator ID in the Name Registry. A bug
  81.    in an early engineering build of A5 prevented use of the NVRAM
  82.    modifier and it was disabled - the adventurous may re-enable
  83.    the code.
  84. • Added secondary interrupt handling, but this does not work
  85.    on the current A5.
  86. • The "fetch debug information" private Status call was removed.
  87.    The driver stores a  pointer to its globals in the name registry
  88.    and the test application fetches the information from there.
  89.  
  90. •• Test application
  91. • Minor changes to track changes in the libraries and headers.
  92. • Some minor reorganization and changes to display routines.
  93. • Rewrote the PCI bus interface library.
  94. • Updated for Code Warrior 1.2
  95. • Added an MPW Makefile.
  96.  
  97. Status (December 23, 1994):
  98.  
  99. • Driver installs, but fails to run successfully.
  100. • Both the MetroWerks and MPW versions compile and install.
  101. • The MetroWerks and MPW versions of the test application
  102.    fail in different ways.
  103. • Dependencies: MPW from ETO 15, MetroWerks Code Warrior 1.2 (GM).
  104.  
  105. Status (January 20, 1995)
  106. • Runs, more or less,  but fails if asynchronous I/O is attempted.
  107. • Can't successfully stop processing using KillIO.
  108. • NVRAM algorithm needs to be tested.
  109.  
  110. Status (January 23, 1995)
  111. • Fixed the NVRAM algorithm - dumb bug.
  112.  
  113. Status (February 5, 1995)
  114. • Updated name registry routines.
  115. • Reimplemented PrepareMemoryForIO.
  116. • Implemented SecondaryInterrupts
  117. • Implemented watchdog timeouts (but, do they work?)
  118. • Removed a lot of debug code: relying on the log library.
  119. • Asynchronous requests randomly fail.
  120.  
  121. Status (Feburary 8, 1995)
  122. • Redesigned the external programming interface: SCSI requests now
  123. use PBRead or PBWrite, with the SCSI-specific parameters passed in
  124. a structure that is referenced by the ioMisc field in the IOParam 
  125. record. This will be compatible with future Mac operating systems that
  126. will not support DMA from user buffers defined in PBControl calls.
  127. • Asynch I/O now seems to work. Maybe PBRead was the answer.
  128. • There's a memory leak somewhere.
  129.  
  130. Status (March 10, 1995 1.0A8 system release)
  131. • Added PrepareMemoryForIO support, removed a lot of work-arounds
  132. for earlier versions.
  133. • Added AAPL,address support.
  134. • Some strange bugs remain; but these may be specific to the
  135. NCI script.
  136. • The memory leak seems to have disappeared.
  137.  
  138. Status (March 13, 1995 1.0A8 system release, "beta candidate")
  139. • Completely rewrote PrepareMemoryForIO. Gave it minimal testing.
  140. • Removed several test applications: now using only MiniTest.
  141. • Much PrepareMemoryForIO testing remains to be done.
  142.  
  143. Status (March 22, 1995 1.0b1)
  144. • Another PrepareMemoryForIO rewrite -- for clarity this time
  145. • Chasing a memory leak. Not necessarily mine.
  146. • The MetroWerks version links against the logging shared library,
  147.    which should be loaded into the Extensions folder on the PCI
  148.    machine. The MPW version compiles against the LogLibrary source,
  149.    because I'm too lazy (and afraid) to change the Makefile.
  150.  
  151. Status (April 5, 1995 1.0b2, 1.0b3 engineering build)
  152. • Debugged at long last -- or so I hope.
  153.  
  154. Programmed by
  155.  
  156. Martin Minow
  157. Apple Computer Inc.
  158. Developer Technical Support
  159.